Smack3.4.1文档翻译：花名册和在线状态，Roster and Presence

花名册 可用于跟踪其它用户的可用性（“是否在线”）。花名册 也允许妳将用户按照分组组织起来，例如“好友”和“同事”。其它 的即时通信系统将花名册称作好友列表、联系人列表等等。

可使用 Connection.getRoster() 方法来获取一个 Roster 实例。

花名册条目

花名册中的每个用户都是使用一个RosterEntry 来表示的，它由以下属性组成：

• •. 一个XMPP地址(例如jsmith@example.com)。

• •. 妳给该用户赋予的一个名字(例如"Joe")。

• •. 该条目在花名册中所从属的分组的列表。如果该花名册条目不属于任何分组，则被称为一个“未分组条目”（"unfiled entry"）。

以下代码片段会输出花名册中的所有条目：

Roster roster = connection.getRoster();

Collection<RosterEntry> entries = roster.getEntries();

for (RosterEntry entry : entries) {

System.out.println(entry);

}

还有一些方法，可用于：获取单个条目；获取未分组条目的列表；或者用来获取某个或所有的花名册分组。

在线状态

花名册 中的每个条目都有与之关联的在线状态对象。 Roster.getPresence(String user) 方法 ，会返回： 代表着 该用户的在线状态的Presence 对象；或者 ，如果 该用户不在线或 妳尝未订阅该用 户的在线状态的话，则会返回 null 。 注意 ： 一般情况下，存在 于花名册中的用户， 总 会有 相应的在线状态对象 与之绑定 ，但是，并非所有状 况下都是如此。

一个用户的在线状态可以是在线或离线。当某个用户在线时，他/她/它的在线状态里可能会包含着更详细的信息，例如他/她/它目前在做什么，是否愿意被打扰，等等。参考Presence类以了解细节。

监听花名册（Roster）和在线状态（Presence）的变更

花名册类的典型用法是，显示出一个由分组和条目组成的树型视图，并且在其中显示出每个条目的当前在线状态。作为一个示例，观摩一下图片中Exodus XMPP 客户端显示的花名册信息。

在线状态信息一般都会经常性地变动，并且花名册中的条目也有可能变动或被删除。要想监听对于花名册和在线状态数据的变更的话，应当使用一个RosterListener。要想监听针对花名册的所有变更的话，该RosterListener应当在登陆到一个XMPP 服务器之前就注册好。以下代码片段，会向该Roster 注册一个RosterListener，它会将花名册中的任何在线状态信息变更都输出到标准输出流中。一个标准的客户端，应当使用类似的代码来根据当前的变更信息更新界面中的花名册。

Roster roster = con.getRoster();

roster.addRosterListener(new RosterListener() {

// 被忽略的事件 public void entriesAdded(Collection<String> addresses) {}

public void entriesDeleted(Collection<String> addresses) {}

public void entriesUpdated(Collection<String> addresses) {}

public void presenceChanged(Presence presence) {

System.out.println("Presence changed: " + presence.getFrom() + " " + presence);

}

});

向花名册中加入条目

花名册和在线状态对象采用一种基于权限的模型，必须经过用户的同意才能将他/她/它们加入到别人的花名册中。这样就保护了用户的隐私，因为，只有被许可的用户才能查看到他/她/它们的在线状态信息。因此，当妳添加一个新的花名册条目时，它会处于一种等待状态，直到对应的用户接受了妳的请求为止。

如果有另一位用户请求订阅妳的在线状态，以便将妳加入到他/她/它的花名册中去的话，妳必须接受或者拒绝该请求。Smack可采用三种不同的方式来处理在线状态订阅请求：

• •.自动接受所有的在线状态订阅请求。

• •.自动拒绝所有的在线状态订阅请求。

• •.手动处理在线状态订阅请求。

具体采用哪种模式 ，可通过 Roster.setSubscriptionMode(Roster.SubscriptionMode) 方法来设置。简单 的客户一般会采用自动处理模式，而完整功能的客户端应当采用手动处理模式 ，由最终用户来决定 是接受还是拒绝每个请求。如果采用手动模式 的话，应当注册一个 PacketListener ，它需要监听类型为 Presence.Type.subscribe 的Presence 数据包。

英拉

波多野结衣

未知美人